home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 3 / Amiga Tools 3.iso / programming / jpegv6 / doc / cjpeg.man < prev    next >
Text File  |  1995-09-05  |  13KB  |  331 lines
  1.  
  2.  
  3.  
  4. CJPEG(1)                                                 CJPEG(1)
  5.  
  6.  
  7. NAME
  8.        cjpeg - compress an image file to a JPEG file
  9.  
  10. SYNOPSIS
  11.        cjpeg [ options ] [ filename ]
  12.  
  13.  
  14. DESCRIPTION
  15.        cjpeg  compresses  the  named  image file, or the standard
  16.        input if no file is named, and produces a  JPEG/JFIF  file
  17.        on  the  standard  output.   The currently supported input
  18.        file formats are: PPM (PBMPLUS color format), PGM (PBMPLUS
  19.        gray-scale  format), BMP, GIF, Targa, and RLE (Utah Raster
  20.        Toolkit format).   (RLE  is  supported  only  if  the  URT
  21.        library is available.)
  22.  
  23. OPTIONS
  24.        All   switch   names  may  be  abbreviated;  for  example,
  25.        -grayscale may be written  -gray  or  -gr.   Most  of  the
  26.        "basic"  switches  can  be abbreviated to as little as one
  27.        letter.  Upper and lower case are equivalent (thus -GIF is
  28.        the  same  as  -gif).  British spellings are also accepted
  29.        (e.g., -greyscale), though for brevity these are not  men­
  30.        tioned below.
  31.  
  32.        The basic switches are:
  33.  
  34.        -quality N
  35.               Scale  quantization tables to adjust image quality.
  36.               Quality is 0 (worst) to 100 (best); default is  75.
  37.               (See below for more info.)
  38.  
  39.        -grayscale
  40.               Create  monochrome  JPEG file from color input.  Be
  41.               sure  to  use  this  switch  when   compressing   a
  42.               grayscale  GIF  file,  because  cjpeg  isn't bright
  43.               enough to notice  whether  a  GIF  file  uses  only
  44.               shades of gray.  By saying -grayscale, you'll get a
  45.               smaller JPEG file that takes less time to  process.
  46.  
  47.        -optimize
  48.               Perform  optimization  of  entropy encoding parame­
  49.               ters.  Without this,  default  encoding  parameters
  50.               are  used.  -optimize usually makes the JPEG file a
  51.               little smaller, but cjpeg runs somewhat slower  and
  52.               needs much more memory.  Image quality and speed of
  53.               decompression are unaffected by -optimize.
  54.  
  55.        -progressive
  56.               Create progressive JPEG file (see below).
  57.  
  58.        -targa Input file is Targa format.  Targa files that  con­
  59.               tain an "identification" field will not be automat­
  60.               ically recognized by cjpeg; for such files you must
  61.  
  62.  
  63.  
  64.                            15 June 1995                         1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. CJPEG(1)                                                 CJPEG(1)
  71.  
  72.  
  73.               specify  -targa  to  make  cjpeg treat the input as
  74.               Targa format.  For most Targa files, you won't need
  75.               this switch.
  76.  
  77.        The  -quality  switch  lets  you trade off compressed file
  78.        size against  quality  of  the  reconstructed  image:  the
  79.        higher  the quality setting, the larger the JPEG file, and
  80.        the closer the output image will be to the original input.
  81.        Normally  you  want  to  use  the  lowest  quality setting
  82.        (smallest file) that decompresses into something  visually
  83.        indistinguishable  from the original image.  For this pur­
  84.        pose the quality setting should be between 50 and 95;  the
  85.        default of 75 is often about right.  If you see defects at
  86.        -quality 75, then go up 5 or 10 counts at a time until you
  87.        are  happy  with  the  output image.  (The optimal setting
  88.        will vary from one image to another.)
  89.  
  90.        -quality 100 will generate a  quantization  table  of  all
  91.        1's,  minimizing  loss in the quantization step (but there
  92.        is still information  loss  in  subsampling,  as  well  as
  93.        roundoff  error).   This setting is mainly of interest for
  94.        experimental purposes.  Quality values above about 95  are
  95.        not  recommended  for normal use; the compressed file size
  96.        goes up dramatically for hardly any gain in  output  image
  97.        quality.
  98.  
  99.        In  the other direction, quality values below 50 will pro­
  100.        duce very small files  of  low  image  quality.   Settings
  101.        around  5 to 10 might be useful in preparing an index of a
  102.        large image library, for example.  Try -quality 2 (or  so)
  103.        for  some  amusing  Cubist effects.  (Note: quality values
  104.        below about 25 generate 2-byte quantization tables,  which
  105.        are considered optional in the JPEG standard.  cjpeg emits
  106.        a warning message when you  give  such  a  quality  value,
  107.        because  some  other JPEG programs may be unable to decode
  108.        the resulting file.  Use -baseline if you need  to  ensure
  109.        compatibility at low quality values.)
  110.  
  111.        The -progressive switch creates a "progressive JPEG" file.
  112.        In this type of JPEG file, the data is stored in  multiple
  113.        scans  of increasing quality.  If the file is being trans­
  114.        mitted over a slow communications link,  the  decoder  can
  115.        use  the  first  scan  to display a low-quality image very
  116.        quickly, and can then improve the display with each subse­
  117.        quent  scan.   The  final image is exactly equivalent to a
  118.        standard JPEG file of the same quality  setting,  and  the
  119.        total  file  size  is  about  the  same --- often a little
  120.        smaller.  Caution: progressive  JPEG  is  not  yet  widely
  121.        implemented,  so  many  decoders  will be unable to view a
  122.        progressive JPEG file at all.
  123.  
  124.        Switches for advanced users:
  125.  
  126.  
  127.  
  128.  
  129.  
  130.                            15 June 1995                         2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. CJPEG(1)                                                 CJPEG(1)
  137.  
  138.  
  139.        -dct int
  140.               Use integer DCT method (default).
  141.  
  142.        -dct fast
  143.               Use fast integer DCT (less accurate).
  144.  
  145.        -dct float
  146.               Use floating-point DCT method.  The float method is
  147.               very  slightly  more  accurate than the int method,
  148.               but is much slower unless  your  machine  has  very
  149.               fast   floating-point  hardware.   Also  note  that
  150.               results  of  the  floating-point  method  may  vary
  151.               slightly across machines, while the integer methods
  152.               should give the same results everywhere.  The  fast
  153.               integer method is much less accurate than the other
  154.               two.
  155.  
  156.        -restart N
  157.               Emit a JPEG restart marker every  N  MCU  rows,  or
  158.               every  N  MCU blocks if "B" is attached to the num­
  159.               ber.  -restart 0 (the  default)  means  no  restart
  160.               markers.
  161.  
  162.        -smooth N
  163.               Smooth  the  input  image  to  eliminate  dithering
  164.               noise.  N, ranging from 1  to  100,  indicates  the
  165.               strength  of  smoothing.   0 (the default) means no
  166.               smoothing.
  167.  
  168.        -maxmemory N
  169.               Set limit for amount of memory to use in processing
  170.               large  images.   Value is in thousands of bytes, or
  171.               millions of bytes if "M" is attached to the number.
  172.               For  example,  -max  4m  selects 4000000 bytes.  If
  173.               more space is needed, temporary files will be used.
  174.  
  175.        -outfile name
  176.               Send  output  image to the named file, not to stan­
  177.               dard output.
  178.  
  179.        -verbose
  180.               Enable debug printout.  More -v's give more output.
  181.               Also, version information is printed at startup.
  182.  
  183.        -debug Same as -verbose.
  184.  
  185.        The  -restart  option  inserts  extra markers that allow a
  186.        JPEG decoder to resynchronize after a transmission  error.
  187.        Without  restart  markers, any damage to a compressed file
  188.        will usually ruin the image from the point of the error to
  189.        the  end of the image; with restart markers, the damage is
  190.        usually confined to the portion of the  image  up  to  the
  191.        next  restart  marker.   Of  course,  the  restart markers
  192.        occupy extra space.  We recommend -restart  1  for  images
  193.  
  194.  
  195.  
  196.                            15 June 1995                         3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. CJPEG(1)                                                 CJPEG(1)
  203.  
  204.  
  205.        that  will  be transmitted across unreliable networks such
  206.        as Usenet.
  207.  
  208.        The -smooth option filters the input  to  eliminate  fine-
  209.        scale  noise.   This  is  often useful when converting GIF
  210.        files to JPEG: a moderate smoothing factor  of  10  to  50
  211.        gets  rid of dithering patterns in the input file, result­
  212.        ing in a smaller JPEG file  and  a  better-looking  image.
  213.        Too  large a smoothing factor will visibly blur the image,
  214.        however.
  215.  
  216.        Switches for wizards:
  217.  
  218.        -baseline
  219.               Force a baseline JPEG file to be  generated.   This
  220.               clamps  quantization  values  to 8 bits even at low
  221.               quality settings.
  222.  
  223.        -qtables file
  224.               Use the quantization tables given in the  specified
  225.               text file.
  226.  
  227.        -qslots N[,...]
  228.               Select  which  quantization  table  to use for each
  229.               color component.
  230.  
  231.        -sample HxV[,...]
  232.               Set JPEG sampling factors for each color component.
  233.  
  234.        -scans file
  235.               Use  the  scan  script  given in the specified text
  236.               file.
  237.  
  238.        The "wizard" switches  are  intended  for  experimentation
  239.        with  JPEG.   If  you don't know what you are doing, don't
  240.        use them.  These switches are documented  further  in  the
  241.        file wizard.doc.
  242.  
  243. EXAMPLES
  244.        This  example compresses the PPM file foo.ppm with a qual­
  245.        ity factor of 60 and saves the output as foo.jpg:
  246.  
  247.               cjpeg -quality 60 foo.ppm > foo.jpg
  248.  
  249. HINTS
  250.        Color GIF files are not the ideal input for JPEG; JPEG  is
  251.        really   intended   for  compressing  full-color  (24-bit)
  252.        images.  In particular, don't  try  to  convert  cartoons,
  253.        line  drawings, and other images that have only a few dis­
  254.        tinct colors.  GIF works great on these,  JPEG  does  not.
  255.        If  you  want to convert a GIF to JPEG, you should experi­
  256.        ment with cjpeg's -quality and -smooth options  to  get  a
  257.        satisfactory  conversion.  -smooth 10 or so is often help­
  258.        ful.
  259.  
  260.  
  261.  
  262.                            15 June 1995                         4
  263.  
  264.  
  265.  
  266.  
  267.  
  268. CJPEG(1)                                                 CJPEG(1)
  269.  
  270.  
  271.        Avoid running an image through a series of  JPEG  compres­
  272.        sion/decompression  cycles.  Image quality loss will accu­
  273.        mulate; after ten or so cycles the image may be noticeably
  274.        worse  than  it  was  after one cycle.  It's best to use a
  275.        lossless format while manipulating an image, then  convert
  276.        to  JPEG format when you are ready to file the image away.
  277.  
  278.        The -optimize option to cjpeg is worth using when you  are
  279.        making  a  "final" version for posting or archiving.  It's
  280.        also a win when you are using low quality settings to make
  281.        very small JPEG files; the percentage improvement is often
  282.        a lot more than it  is  on  larger  files.   (At  present,
  283.        -optimize mode is always selected when generating progres­
  284.        sive JPEG files.)
  285.  
  286. ENVIRONMENT
  287.        JPEGMEM
  288.               If this environment variable is set, its  value  is
  289.               the  default  memory limit.  The value is specified
  290.               as described for the  -maxmemory  switch.   JPEGMEM
  291.               overrides the default value specified when the pro­
  292.               gram was compiled, and itself is overridden  by  an
  293.               explicit -maxmemory.
  294.  
  295. SEE ALSO
  296.        djpeg(1), jpegtran(1), rdjpgcom(1), wrjpgcom(1)
  297.        ppm(5), pgm(5)
  298.        Wallace,  Gregory  K.  "The JPEG Still Picture Compression
  299.        Standard", Communications of the ACM, April 1991 (vol. 34,
  300.        no. 4), pp. 30-44.
  301.  
  302. AUTHOR
  303.        Independent JPEG Group
  304.  
  305. BUGS
  306.        Arithmetic coding is not supported for legal reasons.
  307.  
  308.        Not  all  variants  of BMP and Targa file formats are sup­
  309.        ported.
  310.  
  311.        The -targa switch is not a bug, it's a feature.  (It would
  312.        be  a bug if the Targa format designers had not been clue­
  313.        less.)
  314.  
  315.        Still not as fast as we'd like.
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.                            15 June 1995                         5
  329.  
  330.  
  331.